---
title: Intro
description: "Welcome to the OpenMind OS (OM1) Developer Guide — your essential resource for building, configuring, and managing agents within the OM1 runtime environment."
---

- [CLI](#cli)
- [Linting and Testing](#linting-and-testing)
  * [Unit Testing](#unit-testing)
- [Adding New Actions](#adding-new-actions)

This guide offers an overview of the OM1 agent runtime system, helping developers understand its core components and workflows.

Inside, you’ll find detailed explanations of OM1’s CLI commands, recommended project structure, step-by-step instructions for adding new actions, and guidance on configuring your agent for different environments. Additionally, the guide includes practical development tips to streamline your workflow, along with a reference to optional environment variables that can be used to customize the runtime behavior of your agents.

Whether you're just getting started with OM1 or looking to optimize an existing project, this guide will equip you with the tools and best practices to develop, deploy, and maintain high-performance agents.

## CLI

The OpenMind OS provides a command-line interface (CLI) to manage agents and projects. 

The main entry point is `src/run.py` which provides the following commands:

- `start`: Start an agent with a specified config

```bash Start an agent with a specified config
python src/run.py start [config_name] [--debug]
```

- `config_name`: Name of the config file (without .json5 extension) in the config directory

- `--debug`: Optional flag to enable debug logging

## Linting and Testing

Maintaining code quality and ensuring your agents work correctly is crucial when developing with OpenMind OS (OM1). This section covers recommended linting and testing practices to help you catch errors early, maintain code consistency, and validate agent behavior before deployment.

To check/format your code, run: 
```bash
uv run ruff check . --fix && uv run black . && uv run isort .
```

To automatically run the lint check before committing, install [pre-commit](https://pre-commit.com/) and execute `pre-commit install`. This ensures that pre-commit checks run before each commit. Additionally, you can manually trigger all checks by running `pre-commit run --all-files`.

### Unit Testing 

To unit test the system, run:
```bash
uv run pytest --log-cli-level=DEBUG -s
```

Use type `hints` and `docstrings` for better code maintainability.

## Adding New Actions

Actions are the core capabilities of an agent. For example, for a robot, these capabilities are actions such as movement and speech. Each action consists of:

1. Interface (`interface.py`): Defines input/output types.
2. Implementation (`implementation/`): Business logic, if any. Otherwise, use passthrough.
3. Connector (`connector/`): Code that connects `OM1` to specific virtual or physical environments, typically through middleware (e.g. custom APIs, `ROS2`, `Zenoh`, or `CycloneDDS`)

Example action structure:

```tree Example Action Structure
actions/
└── move_{unique_hardware_id}/
    ├── interface.py      # Defines MoveInput/Output
    ├── implementation/
    │   └── passthrough.py
    └── connector/
        ├── ros2.py       # Maps OM1 data/commands to hardware layers and robot middleware
        ├── zenoh.py
        └── unitree.py
```

In general, each robot will have specific capabilities, and therefore, each action will be hardware specific. For example, if you are adding support for the Unitree G1 Humanoid version 13.2b, which supports a new movement subtype such as `dance_2`, you could name the updated action `move_unitree_g1_13_2b` and select that action in your `unitree_g1.json` configuration file.


